From 08cc83406142f84157a4b25aeee6cc0d31dffd9e Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 10 Jun 2007 06:52:51 +0000 Subject: [PATCH] Update docs Deprecate gtk_widget_{ref,unref} 2007-06-09 Matthias Clasen * gtk/gtkwidget.c: * gtk/gtkscrolledwindow.c: Update docs * gtk/gtkwidget.h: Deprecate gtk_widget_{ref,unref} * gtk/tmpl/gtkbindings.sgml: * gtk/tmpl/gtkrc.sgml: * gtk/tmpl/gtkwidget.sgml: * gtk/tmpl/gtkrecentmanager.sgml: * gtk/*.sgml: * gtk/tmpl/gtkstock.sgml: * gtk/gtk-sections.txt: Updates svn path=/trunk/; revision=18090 --- ChangeLog | 4 + docs/reference/ChangeLog | 10 + docs/reference/gtk/Makefile.am | 1 + docs/reference/gtk/building.sgml | 29 ++- docs/reference/gtk/directfb.sgml | 71 +------ docs/reference/gtk/gtk-docs.sgml | 20 +- docs/reference/gtk/gtk-sections.txt | 5 + .../gtk/migrating-GtkAboutDialog.sgml | 4 +- docs/reference/gtk/migrating-GtkComboBox.sgml | 4 +- .../gtk/migrating-GtkLinkButton.sgml | 6 +- docs/reference/gtk/migrating-checklist.sgml | 33 ++- docs/reference/gtk/question_index.sgml | 193 +++++++++--------- docs/reference/gtk/running.sgml | 44 ++-- docs/reference/gtk/text_widget.sgml | 43 ++-- docs/reference/gtk/tmpl/gtkbindings.sgml | 2 +- docs/reference/gtk/tmpl/gtkbox.sgml | 31 +-- docs/reference/gtk/tmpl/gtkrc.sgml | 20 +- docs/reference/gtk/tmpl/gtkrecentmanager.sgml | 28 +-- docs/reference/gtk/tmpl/gtkstock.sgml | 8 + docs/reference/gtk/tmpl/gtkwidget.sgml | 20 +- docs/reference/gtk/tree_widget.sgml | 3 +- gtk/gtkbox.c | 4 +- gtk/gtkscrolledwindow.c | 5 + gtk/gtkwidget.c | 10 +- gtk/gtkwidget.h | 4 +- 25 files changed, 302 insertions(+), 300 deletions(-) diff --git a/ChangeLog b/ChangeLog index 8652d71a7c..95e06ec261 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2007-06-09 Matthias Clasen + * gtk/gtkwidget.c: + * gtk/gtkscrolledwindow.c: Update docs + * gtk/gtkwidget.h: Deprecate gtk_widget_{ref,unref} + * gtk/gtkbox.c: Move docs inline. * gtk/gtkrange.c: diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 4dacfab8b4..3c588e06bd 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,15 @@ 2007-06-09 Matthias Clasen + * gtk/tmpl/gtkbindings.sgml: + * gtk/tmpl/gtkrc.sgml: + * gtk/tmpl/gtkwidget.sgml: + * gtk/tmpl/gtkrecentmanager.sgml: + * gtk/*.sgml: + * gtk/tmpl/gtkstock.sgml: + * gtk/gtk-sections.txt: Updates + + * gtk/Makefile.am: Exclude another private header + * gtk/tmpl/gtkbox.sgml: Move docs inline 2007-06-08 Matthias Clasen diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 451bc8012b..ecd8b94d41 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -90,6 +90,7 @@ IGNORE_HFILES= \ gtkxembed.h \ gtkwin32embed.h \ gtkwin32embedwidget.h \ + gtkwindow-decorate.h \ xdgmime \ xembed.h diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml index 02d953935f..ffbb43c49c 100644 --- a/docs/reference/gtk/building.sgml +++ b/docs/reference/gtk/building.sgml @@ -45,11 +45,12 @@ How to compile GTK+ itself of the tools are already included in the source packages. But it's useful to know a bit about how packages that use these tools work. A source package is distributed as a - tar.gz file which you unpack into a - directory full of the source files as follows: + tar.gz or tar.bz2 file + which you unpack into a directory full of the source files as follows: tar xvfz gtk+-2.0.0.tar.gz + tar xvfj gtk+-2.0.0.tar.bz2 In the toplevel of the directory that is created, there will be @@ -142,7 +143,7 @@ How to compile GTK+ itself needed for that library along with version number information.) The version of pkg-config needed to build GTK+ is mirrored in the dependencies directory - on the GTK+ FTP + on the GTK+ FTP site. @@ -331,6 +332,10 @@ How to compile GTK+ itself --disable-xkb --enable-xkb + + --disable-xinerama + --enable-xinerama + --disable-gtk-doc --enable-gtk-doc @@ -339,7 +344,7 @@ How to compile GTK+ itself --with-xinput=[no|yes] - --with-gdktarget=[x11|linux-fb|win32] + --with-gdktarget=[x11|linux-fb|win32|quartz|directfb] --disable-shadowfb @@ -480,6 +485,18 @@ How to compile GTK+ itself + + <systemitem>--disable-xinerama</systemitem> and + <systemitem>--enable-xinerama</systemitem> + + + By default the configure script will try + to link against the Xinerama libraries if they are found. + These options can be used to explicitly control whether + Xinerama should be used. + + + <systemitem>--disable-gtk-doc</systemitem> and <systemitem>--enable-gtk-doc</systemitem> @@ -519,7 +536,9 @@ How to compile GTK+ itself Toggles between the supported backends for GDK. The default is x11, unless the platform is Windows, in which - case the default is win32. + case the default is win32. Other supported backends are + the quartz backend for OS X, and the DirectFB backend + for the Linux framebuffer. diff --git a/docs/reference/gtk/directfb.sgml b/docs/reference/gtk/directfb.sgml index d8781feb2d..a012f6cd92 100644 --- a/docs/reference/gtk/directfb.sgml +++ b/docs/reference/gtk/directfb.sgml @@ -31,75 +31,10 @@ system. Build requirements -Beyond the usual GTK+ build requirements, the DirectFB backend (obviously) needs -the DirectFB libraries (at least 0.9.21) and Cairo compiled with DirectFB support. +Beyond the usual GTK+ build requirements, the DirectFB backend (obviously) +needs the DirectFB libraries (at least 0.9.21) and cairo compiled with +DirectFB support. - - - - - diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 0a008ed71f..b8c2e3bea1 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -263,38 +263,31 @@ string utilities, file utilities, a main loop abstraction, and so on. Pango - Pango is a library for internationalized text handling. It centers -around the PangoLayout object, representing -a paragraph of text. -Pango provides the engine for GtkTextView, -GtkLabel, -GtkEntry, and +around the #PangoLayout object, representing a paragraph of text. +Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and other widgets that display text. - ATK - ATK is the Accessibility Toolkit. It provides a set of generic interfaces allowing accessibility technologies to interact with a graphical user interface. For example, a screen reader uses ATK to discover the text in an interface and read it to blind users. GTK+ widgets have built-in support for accessibility using the ATK framework. - GdkPixbuf -This is a small library which allows you to create GdkPixbuf +This is a small library which allows you to create #GdkPixbuf ("pixel buffer") objects from image data or image files. -Use a GdkPixbuf in combination with GtkImage to display images. +Use a #GdkPixbuf in combination with #GtkImage to display images. @@ -310,11 +303,8 @@ on X11, Windows, and the Linux framebuffer device. GTK+ - The GTK+ library itself contains widgets, -that is, GUI components such as GtkButton or -GtkTextView. - +that is, GUI components such as #GtkButton or #GtkTextView. diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt index 9da0b3bfb8..5aed8ff235 100644 --- a/docs/reference/gtk/gtk-sections.txt +++ b/docs/reference/gtk/gtk-sections.txt @@ -4395,6 +4395,7 @@ gtk_tree_store_set_column_types gtk_tree_store_set_value gtk_tree_store_set gtk_tree_store_set_valist +gtk_tree_store_set_valuesv gtk_tree_store_remove gtk_tree_store_insert gtk_tree_store_insert_before @@ -4478,6 +4479,7 @@ gtk_tree_view_column_cell_get_position gtk_tree_view_column_cell_is_visible gtk_tree_view_column_focus_cell gtk_tree_view_column_queue_resize +gtk_tree_view_column_get_tree_view GTK_TREE_VIEW_COLUMN GTK_IS_TREE_VIEW_COLUMN @@ -4828,6 +4830,7 @@ gtk_list_store_set_column_types gtk_list_store_set gtk_list_store_set_valist gtk_list_store_set_value +gtk_list_store_set_valuesv gtk_list_store_remove gtk_list_store_insert gtk_list_store_insert_before @@ -5134,6 +5137,7 @@ gtk_widget_modify_bg gtk_widget_modify_text gtk_widget_modify_base gtk_widget_modify_font +gtk_widget_modify_cursor gtk_widget_create_pango_context gtk_widget_get_pango_context gtk_widget_create_pango_layout @@ -5973,6 +5977,7 @@ GTK_STOCK_DIALOG_INFO GTK_STOCK_DIALOG_QUESTION GTK_STOCK_DIALOG_WARNING GTK_STOCK_DIRECTORY +GTK_STOCK_DISCARD GTK_STOCK_DISCONNECT GTK_STOCK_DND GTK_STOCK_DND_MULTIPLE diff --git a/docs/reference/gtk/migrating-GtkAboutDialog.sgml b/docs/reference/gtk/migrating-GtkAboutDialog.sgml index 10561f3f2f..141e633113 100644 --- a/docs/reference/gtk/migrating-GtkAboutDialog.sgml +++ b/docs/reference/gtk/migrating-GtkAboutDialog.sgml @@ -56,8 +56,8 @@ g_object_unref (pixbuf); If the g_object_new() construction scares you, you can also use - gtk_about_dialog_new() to construct the dialog and then use the setters for - the individual properties. + gtk_about_dialog_new() to construct the dialog and then use the + setters for the individual properties. diff --git a/docs/reference/gtk/migrating-GtkComboBox.sgml b/docs/reference/gtk/migrating-GtkComboBox.sgml index d191be79f7..ce17dff68f 100644 --- a/docs/reference/gtk/migrating-GtkComboBox.sgml +++ b/docs/reference/gtk/migrating-GtkComboBox.sgml @@ -58,8 +58,8 @@ gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item"); gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item"); gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item"); - In order to react to the user's selection, connect to the "changed" - signal on the combo box and use gtk_combo_box_get_active() + In order to react to the user's selection, connect to the + #GtkComboBox::changed signal and use gtk_combo_box_get_active() to retrieve the index of the selected item. diff --git a/docs/reference/gtk/migrating-GtkLinkButton.sgml b/docs/reference/gtk/migrating-GtkLinkButton.sgml index fe8ef22314..204639f3c3 100644 --- a/docs/reference/gtk/migrating-GtkLinkButton.sgml +++ b/docs/reference/gtk/migrating-GtkLinkButton.sgml @@ -11,15 +11,15 @@ Porting an application from GnomeHRef to #GtkLinkButton is very simple. #GtkLinkButton does not have a - default action for "clicked" signal. So instead of simply creating - the widget + default action for #GtkButton::clicked signal. So instead of simply + creating the widget GtkWidget *button; button = gnome_href_new (url, ""); you will have to handle the activation of the #GtkLinkButton, using - the "clicked" signal for instance + the ::clicked signal for instance static void link_button_clicked_cb (GtkWidget *widget, diff --git a/docs/reference/gtk/migrating-checklist.sgml b/docs/reference/gtk/migrating-checklist.sgml index a5e8f3a87d..712cf5de4e 100644 --- a/docs/reference/gtk/migrating-checklist.sgml +++ b/docs/reference/gtk/migrating-checklist.sgml @@ -22,7 +22,7 @@ - The #GtkWidget::popup_menu signal instructs the widget for which + The #GtkWidget::popup-menu signal instructs the widget for which it is emitted to create a context-sensitive popup menu. By default, the key binding mechanism is set to emit this signal when the @@ -75,7 +75,7 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event) - In your ::button-press handler, call this function + In your #GtkWidget::button-press-event handler, call this function when you need to pop up a menu: @@ -97,7 +97,7 @@ my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event) - Implement a handler for the ::popup-menu signal: + Implement a handler for the #GtkWidget::popup-menu signal: @@ -124,10 +124,10 @@ my_widget_popup_menu_handler (GtkWidget *widget) provide your own menu-positioning function in the case where the event is - NULL. This function should compute the - desired position for a menu when it is invoked through the - keyboard. For example, #GtkEntry aligns the - top edge of its popup menu with the bottom edge of the entry. + %NULL. This function should compute the desired position for + a menu when it is invoked through the keyboard. For example, + #GtkEntry aligns the top edge of its popup menu with the bottom + edge of the entry. @@ -137,8 +137,7 @@ my_widget_popup_menu_handler (GtkWidget *widget) able to take the keyboard focus. In general, widgets should be fully usable through the keyboard and not just the mouse. The very first step of this is to ensure that your widget - turns on the %GTK_CAN_FOCUS flag. + turns on the %GTK_CAN_FOCUS flag. @@ -180,7 +179,7 @@ my_widget_popup_menu_handler (GtkWidget *widget) Regions have an internal representation that is accessible as a - list of rectangles. To turn the + list of rectangles. To turn the GdkEventExpose.region field into such a list, use gdk_region_get_rectangles(): @@ -215,12 +214,10 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) Why - With - gtk_accelerator_get_default_mod_mask() - you can test for modifier keys reliably; this way your key - event handlers will work correctly even if - NumLock or CapsLock are - activated. + With gtk_accelerator_get_default_mod_mask() you can test for + modifier keys reliably; this way your key event handlers will + work correctly even if NumLock or + CapsLock are activated. @@ -230,7 +227,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) indicates the modifier state at the time the key was pressed. Modifiers are keys like Control and NumLock. When implementing a - #GtkWidget::key_press_event handler, you should use + #GtkWidget::key-press-event handler, you should use gtk_accelerator_get_default_mod_mask() to test against modifier keys. This function returns a bit mask which encompasses all the modifiers which the user may be @@ -298,7 +295,7 @@ my_widget_key_press_event_handler (GtkWidget *widget, GdkEventKey *event) gtk_window_set_icon_name()) and images (see gtk_image_set_icon_name()). In GTK+ 2.8, you can also use named icons for drag-and-drop (see gtk_drag_source_set_icon_name()) and in treeview cells (see the - #GtkCellRendererPixbuf:icon_name property). + #GtkCellRendererPixbuf:icon-name property). diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml index 6c1f32fff3..d5490fb64e 100644 --- a/docs/reference/gtk/question_index.sgml +++ b/docs/reference/gtk/question_index.sgml @@ -59,7 +59,7 @@ See the documentation on this topic. -How do I port from one GTK+ +How do I port from one GTK+ version to another? @@ -96,17 +96,17 @@ from functions? -See the documentation for #GObject and #GtkObject. For #GObject note specifically -g_object_ref() and g_object_unref(). #GtkObject is a subclass of #GObject so the -same points apply, except that it has a "floating" state (explained in its -documentation). +See the documentation for #GObject and #GtkObject. For #GObject note +specifically g_object_ref() and g_object_unref(). #GtkObject is a subclass +of #GObject so the same points apply, except that it has a "floating" state +(explained in its documentation). For strings returned from functions, they will be declared "const" (using -#G_CONST_RETURN) if they should not be freed. Non-const strings should be freed -with g_free(). Arrays follow the same rule. (If you find an exception to the rules, -please report a bug to http://bugzilla.gnome.org.) @@ -135,8 +135,9 @@ reference counting, not floating reference counting. -To to get this, you must acquire a reference to the widget and drop the floating -reference (ref and sink in GTK+ parlance) after creating it: +To to get this, you must acquire a reference to the widget and drop the +floating reference (ref and sink in GTK+ parlance) after +creating it: foo = gtk_foo_new (); g_object_ref (foo); @@ -165,10 +166,9 @@ How do I use GTK+ with threads? -This is covered in the -GDK threads documentation. -See also the GThread documentation for portable -threading primitives. +This is covered in the GDK threads +documentation. See also the GThread +documentation for portable threading primitives. @@ -184,8 +184,8 @@ How do I internationalize a GTK+ program? Most people use GNU gettext, already required in order to install GLib. On a UNIX -or Linux system with gettext installed, type info -gettext to read the documentation. +or Linux system with gettext installed, type info gettext +to read the documentation. The short checklist on how to use gettext is: call bindtextdomain() so gettext @@ -199,15 +199,17 @@ follows for convenience: #define N_(x) x -You use N_() (N stands for no-op) to mark a string for translation in a context -where a function call to gettext() is not allowed, such as in an array initializer. +You use N_() (N stands for no-op) to mark a string for translation in a +context where a function call to gettext() is not allowed, such as in an +array initializer. You eventually have to call gettext() on the string to actually fetch the -translation. _() both marks the string for translation and actually translates it. +translation. _() both marks the string for translation and actually +translates it. Nowadays, GLib provides the common shorthand macros in the header file -gi18n.h, so you don't have to define them yourself, just -include that header. +gi18n.h, so you don't have to define them yourself, +just include that header. Code using these macros ends up looking like this: @@ -230,10 +232,11 @@ Code using these macros ends up looking like this: -Libraries using gettext should use dgettext() instead of gettext(), which allows -them to specify the translation domain each time they ask for a translation. Libraries -should also avoid calling textdomain(), since they'll be specifying the domain instead -of using the default.For dgettext() the _() macro can be defined as: +Libraries using gettext should use dgettext() instead of gettext(), which +allows them to specify the translation domain each time they ask for a +translation. Libraries should also avoid calling textdomain(), since they +will be specifying the domain instead of using the default. For dgettext() +the _() macro can be defined as: #define _(x) dgettext ("MyDomain", x) @@ -241,9 +244,9 @@ of using the default.For dgettext() the _() macro can be defined as: -Again, GLib comes with the gi18n-lib.h, saving you the trouble -of defining the macros by hand. The macros in that header expect the translation -domain to be specified by the %GETTEXT_PACKAGE macro. +Again, GLib comes with the gi18n-lib.h, saving you the +trouble of defining the macros by hand. The macros in that header expect the +translation domain to be specified by the %GETTEXT_PACKAGE macro. @@ -258,10 +261,9 @@ How do I use non-ASCII characters in GTK+ programs ? GTK+ uses Unicode (more exactly -UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a - sequence of one to six bytes and has a number of nice - properties which make it a good choice for working with Unicode - text in C programs: +UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of +one to six bytes and has a number of nice properties which make it a good +choice for working with Unicode text in C programs: ASCII characters are encoded by their familiar ASCII codepoints. @@ -270,21 +272,22 @@ ASCII characters are encoded by their familiar ASCII codepoints. ASCII characters never appear as part of any other character. -The zero byte doesn't occur as part of a character, so that UTF-8 strings can - be manipulated with the usual C library functions for - handling zero-terminated strings. +The zero byte doesn't occur as part of a character, so that UTF-8 strings +can be manipulated with the usual C library functions for handling +zero-terminated strings. More information about Unicode and UTF-8 can be found in the -UTF-8 and Unicode FAQ for Unix/Linux. +UTF-8 and Unicode i +FAQ for Unix/Linux. GLib provides functions for converting strings between UTF-8 and other - encodings, see g_locale_to_utf8() and g_convert(). +encodings, see g_locale_to_utf8() and g_convert(). Text coming from external sources (e.g. files or user input), has to be - converted to UTF-8 before being handed over to GTK+. The - following example writes the content of a IS0-8859-1 encoded text - file to stdout: +converted to UTF-8 before being handed over to GTK+. The following example +writes the content of a IS0-8859-1 encoded text file to +stdout: gchar *text, *utf8_text; gsize length; @@ -308,7 +311,7 @@ else For string literals in the source code, there are several alternatives for - handling non-ASCII content: +handling non-ASCII content: direct UTF-8 @@ -334,8 +337,9 @@ very convenient. Be careful when mixing hexadecimal escapes with ordinary text; If the string literals can be represented in an encoding which your toolchain can handle (e.g. IS0-8859-1), you can write your source files in that encoding -and use g_convert() to convert the strings to UTF-8 at runtime. Note that this has -some runtime overhead, so you may want to move the conversion out of inner loops. +and use g_convert() to convert the strings to UTF-8 at runtime. Note that this +has some runtime overhead, so you may want to move the conversion out of inner +loops. @@ -364,7 +368,7 @@ There are two ways to approach this. The GTK+ header files use the subset of C that's also valid C++, so you can simply use the normal GTK+ API in a C++ program. Alternatively, you can use a "C++ binding" such as gtkmm -which provides a C++-native API. +which provides a native C++ API. When using GTK+ directly, keep in mind that only functions can be @@ -404,7 +408,7 @@ How do I use GTK+ with other non-C languages? See the list of language bindings on http://www.gtk.org. +url="http://www.gtk.org">http://www.gtk.org. @@ -419,15 +423,16 @@ How do I load an image or animation from a file? -To load an image file straight into a display widget, use gtk_image_new_from_file() - If the file load fails, gtk_image_new_from_file() will display no -image graphic — to detect a failed load yourself, use gdk_pixbuf_new_from_file() -directly, then gtk_image_new_from_pixbuf().. -To load an image for another purpose, use gdk_pixbuf_new_from_file(). To load an -animation, use gdk_pixbuf_animation_new_from_file(). -gdk_pixbuf_animation_new_from_file() can also load non-animated images, so use it -in combination with gdk_pixbuf_animation_is_static_image() to load a file of unknown -type. +To load an image file straight into a display widget, use +gtk_image_new_from_file() If the file load fails, +gtk_image_new_from_file() will display no image graphic — to detect +a failed load yourself, use gdk_pixbuf_new_from_file() directly, then +gtk_image_new_from_pixbuf().. +To load an image for another purpose, use gdk_pixbuf_new_from_file(). To i +load an animation, use gdk_pixbuf_animation_new_from_file(). +gdk_pixbuf_animation_new_from_file() can also load non-animated images, so +use it in combination with gdk_pixbuf_animation_is_static_image() to load a +file of unknown type. To load an image or animation file asynchronously (without blocking), use @@ -503,21 +508,22 @@ to the GNOME 2.0 platform. -Why are types not registered if I use their GTK_TYPE_BLAH macro ? +Why are types not registered if I use their GTK_TYPE_BLAH +macro ? The GTK_TYPE_BLAH macros are defined as calls to -gtk_blah_get_type(), and the _get_type() functions -are declared as G_GNUC_CONST which allows the compiler to optimize +gtk_blah_get_type(), and the _get_type() i +functions are declared as %G_GNUC_CONST which allows the compiler to optimize the call away if it appears that the value is not being used. -A common workaround for this problem is to store the result in a volatile variable, -which keeps the compiler from optimizing the call away. +A common workaround for this problem is to store the result in a volatile +variable, which keeps the compiler from optimizing the call away. volatile GType dummy = GTK_TYPE_BLAH; @@ -595,9 +601,9 @@ should use the #GtkTextView widget. Do not use the deprecated widget #GtkText in newly-written code, it has a number of problems that are best avoided. -If you only have a small amount of text, #GtkLabel may also be appropriate of course. -It can be made selectable with gtk_label_set_selectable(). For a single-line text -entry, see #GtkEntry. +If you only have a small amount of text, #GtkLabel may also be appropriate +of course. It can be made selectable with gtk_label_set_selectable(). For a +single-line text entry, see #GtkEntry. @@ -610,9 +616,9 @@ entry, see #GtkEntry. -#GtkImage can display images in just about any format GTK+ understands. You can also -use #GtkDrawingArea if you need to do something more complex, such as draw text or -graphics over the top of the image. +#GtkImage can display images in just about any format GTK+ understands. +You can also use #GtkDrawingArea if you need to do something more complex, +such as draw text or graphics over the top of the image. @@ -644,14 +650,15 @@ How do I change the color of a widget? See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(), and gtk_widget_modify_text(). See GTK+ -resource files for more discussion. You can also change widget color by -installing a resource file and parsing it with gtk_rc_add_default_file(). +resource files for more discussion. You can also change widget color +by installing a resource file and parsing it with gtk_rc_add_default_file(). The advantage of a resource file is that users can then override the color you've chosen. -To change the background color for widgets such as #GtkLabel that have no -background, place them in a #GtkEventBox and set the background of the event box. +To change the background color for widgets such as #GtkLabel that have +no background, place them in a #GtkEventBox and set the background of the +event box. @@ -661,9 +668,9 @@ How do I change the font of a widget? -This has several possible answers, depending on what exactly you want to achieve. -One option is gtk_widget_modify_font(). Note that this function can be used to -change only the font size, as in the following example: +This has several possible answers, depending on what exactly you want to +achieve. One option is gtk_widget_modify_font(). Note that this function +can be used to change only the font size, as in the following example: PangoFontDesc *font_desc = pango_font_description_new (); pango_font_description_set_size (font_desc, 40); @@ -672,23 +679,24 @@ change only the font size, as in the following example: -If you want to make the text of a label larger, you can use gtk_label_set_markup(): +If you want to make the text of a label larger, you can use +gtk_label_set_markup(): gtk_label_set_markup (label, "<big>big text</big>"); This is preferred for many apps because it's a relative size to the -user's chosen font size. See g_markup_escape_text() if you are constructing such -strings on the fly. +user's chosen font size. See g_markup_escape_text() if you are +constructing such strings on the fly. You can also change the font of a widget by putting gtk-font-name = "Sans 30" -in a resource file and parsing it with gtk_rc_add_default_file(). The advantage of -a resource file is that users can then override the font you've chosen. See -GTK+ resource files for more -discussion. +in a resource file and parsing it with gtk_rc_add_default_file(). +The advantage of a resource file is that users can then override the font you +have chosen. See GTK+ resource files +for more discussion. @@ -738,9 +746,10 @@ How do I make a text widget display its complete contents in a specific font? -If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select the -font, the inserted text will have the desired appearance, but text typed in by the -user before or after the tagged block will appear in the default style. +If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select +the font, the inserted text will have the desired appearance, but text typed +in by the user before or after the tagged block will appear in the default +style. To ensure that all text has the desired appearance, use gtk_widget_modify_font() @@ -789,8 +798,8 @@ How do I associate some data with a row in the tree? Remember that the #GtkTreeModel columns don't necessarily have to be displayed. -So you can put non-user-visible data in your model just like any other data, and -retrieve it with gtk_tree_model_get(). See the +So you can put non-user-visible data in your model just like any other data, +and retrieve it with gtk_tree_model_get(). See the tree widget overview. @@ -818,9 +827,10 @@ How do I put an image and some text in the same column? -You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn using -gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). So pack both -a #GtkCellRendererPixbuf and a #GtkCellRendererText into the column. +You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn +using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). +So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the +column. @@ -834,8 +844,9 @@ gtk_list_store_set() and gtk_tree_store_set(), but can't read it back? Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel -interface. Consequentially, the can use any function this interface implements. -The easiest way to read a set of data back is to use gtk_tree_model_get(). +interface. Consequentially, the can use any function this interface +implements. The easiest way to read a set of data back is to use +gtk_tree_model_get(). @@ -846,8 +857,8 @@ How do I change the way that numbers are formatted by #GtkTreeView? Use gtk_tree_view_insert_column_with_data_func() -or gtk_tree_view_column_set_cell_data_func() and do the conversion from number to -string yourself (with, say, g_strdup_printf()). +or gtk_tree_view_column_set_cell_data_func() and do the conversion from i +number to string yourself (with, say, g_strdup_printf()). diff --git a/docs/reference/gtk/running.sgml b/docs/reference/gtk/running.sgml index 868bb61451..206e470b7a 100644 --- a/docs/reference/gtk/running.sgml +++ b/docs/reference/gtk/running.sgml @@ -20,9 +20,9 @@ How to run and debug your GTK+ application All GTK+ applications support a number of standard commandline -options. These are removed from argv by gtk_init(). Modules may parse and remove -further options. The X11 and +options. These are removed from argv by gtk_init(). +Modules may parse and remove further options. The +X11 and Windows GDK backends parse some additional commandline options. @@ -80,7 +80,7 @@ list them here for completeness nevertheless. <systemitem>--class <replaceable>class</replaceable></systemitem> -Sets the program class; see gdk_set_program_class(). +Sets the program class; see gdk_set_program_class(). @@ -97,10 +97,9 @@ Sets the program name. A list of debug options -to turn on in addition to those -specified in the GDK_DEBUG environment variable. -This option is only available if GTK+ has been configured with -. +to turn on in addition to those specified in the GDK_DEBUG +environment variable. This option is only available if GTK+ has been +configured with . @@ -109,8 +108,7 @@ This option is only available if GTK+ has been configured with A list of debug options -to turn off. -This option is only available if GTK+ has been configured with +to turn off. This option is only available if GTK+ has been configured with . @@ -184,7 +182,8 @@ additional environment variables. - The special value all can be used to turn on all debug options. + The special value all can be used to turn on all + debug options. @@ -202,12 +201,13 @@ additional environment variables. Specifies a list of directories to search when GTK+ is looking for dynamically loaded objects such as the modules specified by - GTK_MODULES, theme engines, and input method - modules. If the path to the dynamically loaded object is given - as an absolute path name, then GTK+ loads it directly. Otherwise, - GTK+ goes in turn through the directories in GTK_PATH, followed - by the directory .gtk-2.0 in the user's home - directory, followed by the system default directory, + GTK_MODULES, theme engines, input method + modules, file system backends and print backends. If the path to + the dynamically loaded object is given as an absolute path name, + then GTK+ loads it directly. + Otherwise, GTK+ goes in turn through the directories in GTK_PATH, + followed by the directory .gtk-2.0 in the user's + home directory, followed by the system default directory, which is libdir/gtk-2.0/modules. (If GTK_EXE_PREFIX is defined, libdir is $GTK_EXE_PREFIX/lib. Otherwise it is the libdir @@ -225,9 +225,10 @@ additional environment variables. --variable=gtk_host gtk+-2.0 to determine this from a script), and type is a directory specific to the type of modules; currently it can be - modules, engines or - immodules corresponding to the three types of - modules above. Either version, + modules, engines, + immodules, filesystems or + printbackends, corresponding to the types of + modules mentioned above. Either version, host, or both may be omitted. GTK+ looks first in the most specific directory, then in directories with fewer components. @@ -328,7 +329,8 @@ nevertheless. Information about XIM support - The special value all can be used to turn on all debug options. + The special value all can be used to turn on all + debug options. diff --git a/docs/reference/gtk/text_widget.sgml b/docs/reference/gtk/text_widget.sgml index 88a766e388..da31a8ee17 100644 --- a/docs/reference/gtk/text_widget.sgml +++ b/docs/reference/gtk/text_widget.sgml @@ -37,8 +37,8 @@ be called "bold" and make the text inside the tag bold. However, the tag concept is more general than that; tags don't have to affect appearance. They can instead affect the behavior of mouse and key presses, "lock" a range of text so the user can't edit it, or countless other things. A tag is -represented by a #GtkTextTag object. One #GtkTextTag can be applied to any number -of text ranges in any number of buffers. +represented by a #GtkTextTag object. One #GtkTextTag can be applied to any +number of text ranges in any number of buffers. @@ -57,35 +57,36 @@ is convenient if you're creating tags on-the-fly). Most text manipulation is accomplished with iterators, represented by a #GtkTextIter. An iterator represents a position between two -characters in the text buffer. #GtkTextIter is a struct designed to be allocated -on the stack; it's guaranteed to be copiable by value and never contain any -heap-allocated data. Iterators are not valid indefinitely; whenever the buffer -is modified in a way that affects the number of characters in the buffer, all -outstanding iterators become invalid. (Note that deleting 5 characters and then -reinserting 5 still invalidates iterators, though you end up with the same -number of characters you pass through a state with a different number). +characters in the text buffer. #GtkTextIter is a struct designed to be +allocated on the stack; it's guaranteed to be copiable by value and never +contain any heap-allocated data. Iterators are not valid indefinitely; +whenever the buffer is modified in a way that affects the number of characters +in the buffer, all outstanding iterators become invalid. (Note that deleting +5 characters and then reinserting 5 still invalidates iterators, though you +end up with the same number of characters you pass through a state with a +different number). Because of this, iterators can't be used to preserve positions across buffer -modifications. To preserve a position, the #GtkTextMark object is ideal. You can -think of a mark as an invisible cursor or insertion point; it floats in the buffer, -saving a position. If the text surrounding the mark is deleted, the mark remains -in the position the text once occupied; if text is inserted at the mark, the -mark ends up either to the left or to the right of the new text, depending on -its gravity. The standard text cursor in left-to-right -languages is a mark with right gravity, because it stays to the right of -inserted text. +modifications. To preserve a position, the #GtkTextMark object is ideal. You +can think of a mark as an invisible cursor or insertion point; it floats in +the buffer, saving a position. If the text surrounding the mark is deleted, +the mark remains in the position the text once occupied; if text is inserted +at the mark, the mark ends up either to the left or to the right of the new +text, depending on its gravity. The standard text +cursor in left-to-right languages is a mark with right gravity, because it +stays to the right of inserted text. Like tags, marks can be either named or anonymous. There are two marks built-in to #GtkTextBuffer; these are named "insert" and "selection_bound" and refer to the insertion point and the -boundary of the selection which is not the insertion point, respectively. If no -text is selected, these two marks will be in the same position. You can manipulate -what is selected and where the cursor appears by moving these marks around. - +boundary of the selection which is not the insertion point, respectively. If +no text is selected, these two marks will be in the same position. You can +manipulate what is selected and where the cursor appears by moving these +marks around. If you want to place the cursor in response to a user action, be sure to use diff --git a/docs/reference/gtk/tmpl/gtkbindings.sgml b/docs/reference/gtk/tmpl/gtkbindings.sgml index 418dc178dc..8df993a95c 100644 --- a/docs/reference/gtk/tmpl/gtkbindings.sgml +++ b/docs/reference/gtk/tmpl/gtkbindings.sgml @@ -243,7 +243,7 @@ Deprecated. - + @object: diff --git a/docs/reference/gtk/tmpl/gtkbox.sgml b/docs/reference/gtk/tmpl/gtkbox.sgml index ab26d6c4f5..6f4d669f4d 100644 --- a/docs/reference/gtk/tmpl/gtkbox.sgml +++ b/docs/reference/gtk/tmpl/gtkbox.sgml @@ -181,17 +181,16 @@ application.) reference to the start (top/left) or end (bottom/right) of the GtkBox. @is_secondary: - @box: -@child: -@expand: -@box -@fill: +@child: +@expand: +@box +@fill: @padding: @@ -222,7 +221,7 @@ application.) @box: -@widget: +@widget: @@ -267,8 +266,8 @@ application.) @box: -@child: -@position: +@child: +@position: @@ -276,11 +275,11 @@ application.) -@box: -@child: -@expand: +@box: +@child: +@expand: @fill: -@padding: +@padding: @pack_type: @@ -291,7 +290,9 @@ application.) @box: @child: -@expand: +@expand: @fill: -@padding: -@pack_type: +@padding: +@pack_type: + + diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml index 13a5ac1687..5a82338037 100644 --- a/docs/reference/gtk/tmpl/gtkrc.sgml +++ b/docs/reference/gtk/tmpl/gtkrc.sgml @@ -952,13 +952,23 @@ Parses resource information directly from a string. -Parses a color in the format expected in a RC file. + -@scanner: a #GtkScanner -@color: a pointer to a #GtkColor structure in which to store the result -@Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token -that was expected but not found. +@scanner: +@color: +@Returns: + + + + + + + +@scanner: +@style: +@color: +@Returns: diff --git a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml b/docs/reference/gtk/tmpl/gtkrecentmanager.sgml index b6acb5b84e..5e0921c609 100644 --- a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml +++ b/docs/reference/gtk/tmpl/gtkrecentmanager.sgml @@ -110,23 +110,17 @@ recently used files list. -Meta-data passed to gtk_recent_manager_add_full(). You should -use #GtkRecentData if you want to control the meta-data associated -to an entry of the recently used files list when you are adding -a new file to it. - - -@display_name: the string to be used when displaying the file - inside a #GtkRecentChooser -@description: a user readable description of the file -@mime_type: the mime type of the file -@app_name: the name of the application that is registering - the file -@app_exec: the command line that should be used when launching - the file -@groups: the list of group names to which the file belongs to -@is_private: whether the file should be displayed only by - the applications that have registered it + + + +@display_name: +@description: +@mime_type: +@app_name: +@app_exec: +@groups: +@is_private: + diff --git a/docs/reference/gtk/tmpl/gtkstock.sgml b/docs/reference/gtk/tmpl/gtkstock.sgml index f6ed550a0d..e4ac541a2d 100644 --- a/docs/reference/gtk/tmpl/gtkstock.sgml +++ b/docs/reference/gtk/tmpl/gtkstock.sgml @@ -275,6 +275,14 @@ The "Directory" icon. @Since: 2.6 + + +The "Discard" item. + + +@Since: 2.12 + + The "Disconnect" icon. diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml index 99a2df0200..e92a7c0011 100644 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkwidget.sgml @@ -323,15 +323,11 @@ gtk_widget_style_get_valist() to obtain the value of a style property. -Emitted when there is a change in the hierarchy to -which a widget belongs. More precisely, a widget is -anchored when its toplevel -ancestor is a #GtkWindow. This signal is emitted when -a widget changes from un-anchored to anchored or vice-versa. + -@widget: the object which received the signal. -@widget2: the toplevel ancestor, or %NULL +@widget: +@widget2: @@ -1979,6 +1975,16 @@ This function is not useful for applications. @font_desc: + + + + + +@widget: +@primary: +@secondary: + + diff --git a/docs/reference/gtk/tree_widget.sgml b/docs/reference/gtk/tree_widget.sgml index 63959004fd..4dee9c0897 100644 --- a/docs/reference/gtk/tree_widget.sgml +++ b/docs/reference/gtk/tree_widget.sgml @@ -195,7 +195,8 @@ gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column); Most applications will need to not only deal with displaying data, but also receiving input events from users. To do this, simply get a - reference to a selection object and connect to the "changed" signal. + reference to a selection object and connect to the + #GtkTreeSelection::changed signal. anchored when its toplevel + * ancestor is a #GtkWindow. This signal is emitted when + * a widget changes from un-anchored to anchored or vice-versa. */ widget_signals[HIERARCHY_CHANGED] = g_signal_new (I_("hierarchy_changed"), @@ -7837,7 +7839,7 @@ gtk_widget_reset_shapes (GtkWidget *widget) * * Return value: the widget that was referenced * - * Deprecated: Use g_object_ref() instead. + * Deprecated:2.12: Use g_object_ref() instead. **/ GtkWidget* gtk_widget_ref (GtkWidget *widget) @@ -7853,7 +7855,7 @@ gtk_widget_ref (GtkWidget *widget) * * Inverse of gtk_widget_ref(). Equivalent to g_object_unref(). * - * Deprecated: Use g_object_unref() instead. + * Deprecated:2.12: Use g_object_unref() instead. **/ void gtk_widget_unref (GtkWidget *widget) diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h index 8db67c10c0..efb2b73244 100644 --- a/gtk/gtkwidget.h +++ b/gtk/gtkwidget.h @@ -444,12 +444,12 @@ GType gtk_widget_get_type (void) G_GNUC_CONST; GtkWidget* gtk_widget_new (GType type, const gchar *first_property_name, ...); -GtkWidget* gtk_widget_ref (GtkWidget *widget); -void gtk_widget_unref (GtkWidget *widget); void gtk_widget_destroy (GtkWidget *widget); void gtk_widget_destroyed (GtkWidget *widget, GtkWidget **widget_pointer); #ifndef GTK_DISABLE_DEPRECATED +GtkWidget* gtk_widget_ref (GtkWidget *widget); +void gtk_widget_unref (GtkWidget *widget); void gtk_widget_set (GtkWidget *widget, const gchar *first_property_name, ...) G_GNUC_NULL_TERMINATED; -- 2.30.2